# Hackware Web Services Wallet

## Overview

Digital wallet that associates transactions and balance to unique users.

## Main goals

- Add and subtract transactions
- Lookup balance
- Support any number of currencies (incluiding company's own currencies)
- Transactions history

## Generic requirements

- Amounts must allow decimals
- Use arbitrary precision (BCMath PHP)

## User stories

- As consumer I want to create a wallet so I can perform further transactions with the same uid. I should be able add an initial amount in any currency of money and this amount could be negative. Independent of which currency I'm using the transaction values should be reasonably consistent on different days.
- As consumer I want to transact money by adding or subtracting balance from an existing wallet so a backer can pay for the services he consumes. Account balance must be consistent with the amount entered within transactions, even after a currency rate has changed. Negative amount transactions must include an expiration date if balance becomes negative after adding it.
- As consumer I want to lookup for current state of a wallet so I can know how much money a backer has available.
- As consumer I want to lookup for the current state of all wallets so I can have a general view.
- As consumer I want to lookup for the transactions history of a wallet so I can know how I've reached the current account balance of a wallet. Should be ordered by descending datetime.
- As consumer I want to filter by start and/or end time of transactions so I can be more granular on my transactions history lookup.
- As consumer I want to optionally include the currency object of transactions history list, so I don't need to look it up with other request.
- As consumer I want to list all existing currencies, so I can know which ones are available.
- As consumer I want to lookup at the current rate of a currency so I can display that information to users.
- As consumer I want to convert currency rates so I can perform operations based on this information.
- As consumer I want to send a notification email to the backer when a transaction is performed so he can have immediate feedback. A payment link must be included if account balance becomes negative. Must include due date and default to the absolute value of account balance.

## Database tables

- currencies: id*, code (char 3), rate (decimal), step (decimal), created_at
- wallets: uid* (string 100), currency_code (fk char 3), balance (decimal), created_at, updated_at, deleted_at
- transactions: id*, wallet_uid (fk sting 100), currency_id (fk char 3), amount (decimal), type (string 100), description (string 255), detail (text), due_at (datetime), created_at, updated_at

## Run it

### Requirements

- BCMath PHP Extension
- [Hawese Core](https://get.hackware.cl/hawese-core/)

### Installation

```
composer require hackware/hawese-wallet
```

#### Environment variables

- `WALLET_TRANSACTION_TYPES` are used to identify the origin of a transaction, it's a comma separated string of choices for `Transaction::$type`. By default only `system` is defined. Required.
- `WALLET_DUE_AFTER` a valid `DateInterval::createFromDateString()` string which defines the `Transaction::$due_at` date if a Wallet has negative balance. Defaults to `1 month`.
- `WALLET_SOURCE_URL` is the place where to download the source code of your version of this project. Required.
- `WALLET_ADD_FUNDS_URL` Link to send with transaction notifications, which allows users to add new funds. Currently coupled to [userland](https://git.hackware.cl/userland) config, as will attach an `auth_token` query param (not more coupled than this). Required.
- `WALLET_REMIND_DUE` valid `DateInterval::createFromDateString()` comma separated string for sending remainders of due transactions X days previous to due date. Defaults to `1 day, 2 days, 3 days, 1 week`.

## Copyright and licensing

Copyright 2019 [Hackware SpA](https://hackware.cl).

This project is licensed under the GNU Affero General Public License v3 or any later version.

### How to comply with license terms?

To comply with license terms you must provide the means to access the source code of your version of the software easily and free of charge to any person that has access to the software, even users which access through a network (i.e. web browser). I've provided an easy way to accomplish this requirement by setting the `WALLET_SOURCE_URL` environment variable, this will show the link on the index page (/) under the JSON `links.wallet_sourcecode` property.

Any modification or inclusion of this source code will inherit the same license, that is, it can't be sublicensed. But since it's a REST API you can consume it with any other software. That means that this software must always respect users freedom, even if the HTTP API is consumed by a privative one.

### Other licensing options

If you want to use the software but are afraid of or can't comply with the license terms we can arrange other license terms for your case. Though most probably I'll not accept if you don't provide your modifications to the software back.
